# Usage

To use **Jupyter MCP Server**, you need to:

1. [Start JupyterLab](#start-jupyterlab)
2. [Configure your preferred MCP client](#configuration)

      We have examples for:
        - [Claude Desktop](./claude_desktop)
        - [Cursor](./cursor)
        - [Cline](./cline)
        - [Windsurf](./windsurf)

      BUT this server is compatible with **any** MCP client — see the growing list in [MCP clients](https://modelcontextprotocol.io/clients). This means that you are **not** limited to the clients listed above.

You can also use [Smithery](#installing-via-smithery) to install Jupyter MCP Server automatically for your preferred client.

## Start JupyterLab

Make sure you have the following packages installed in your environment. The collaboration package is needed as the modifications made on the notebook can be seen thanks to [Jupyter Real Time Collaboration](https://jupyterlab.readthedocs.io/en/stable/user/rtc.html).

```bash
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 ipykernel
pip uninstall -y pycrdt datalayer_pycrdt
pip install datalayer_pycrdt==0.12.17
```

Then, start JupyterLab with the following command.

```bash
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0
```

You can also run `make jupyterlab` if you cloned the repository.

:::note
The `--ip` is set to `0.0.0.0` to allow the MCP server running in a Docker container to access your local JupyterLab.
:::

## Configuration

Use the following configuration file to set up the Jupyter MCP Server for your preferred MCP client.
Note that the configuration is dependent on the operating system you are using.

:::important
Ensure the `port` of the `SERVER_URL`and `TOKEN` match those used in the `jupyter lab` command.

The `NOTEBOOK_PATH` should be relative to the directory where JupyterLab was started.
:::

### MacOS and Windows

```json
{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SERVER_URL",
        "-e",
        "TOKEN",
        "-e",
        "NOTEBOOK_PATH",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "SERVER_URL": "http://host.docker.internal:8888",
        "TOKEN": "MY_TOKEN",
        "NOTEBOOK_PATH": "notebook.ipynb"
      }
    }
  }
}
```

### Linux

```json
{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SERVER_URL",
        "-e",
        "TOKEN",
        "-e",
        "NOTEBOOK_PATH",
        "--network=host",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "SERVER_URL": "http://localhost:8888",
        "TOKEN": "MY_TOKEN",
        "NOTEBOOK_PATH": "notebook.ipynb"
      }
    }
  }
}
```


## Installing via Smithery

To install Jupyter MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@datalayer/jupyter-mcp-server):

```bash
npx -y @smithery/cli install @datalayer/jupyter-mcp-server --client claude
```
